home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / comms / other / aminetparse / aminetparse.doc < prev    next >
Text File  |  1999-06-14  |  12KB  |  272 lines
  1.                             AminetParse v1.09
  2.  
  3.                    © 1997-1999 by Daniel J. Andrea II
  4.  
  5.  
  6. NOTE:  This software is offered as GIFTWARE.  If you like it, then you can
  7. send me something in payment of your choice (other programs, disks, computers,
  8. cars, etc.) at the address at the end of this document.  No warranty of any
  9. kind is offered with this software or implied, or for suitability of purpose.
  10. It's use is entirely at your own risk.  No fees can be charged for this
  11. software, other than the nominal fees for the cost of magnetic media and
  12. copying of the software onto that media, not to exceed the amount of US $5 for
  13. a disk containing this software.  Copies of this software must include this
  14. documentation file for redistribution through Fred Fish or other similar
  15. software collections.
  16.  
  17. Attention:  This software's Aminet status has been slightly changed.  I continue
  18. to receive offers for a 'free' Aminet CD as a contibutor.  However, the cost to
  19. me is anything but free.  It would cost nearly as much to order it from Germany
  20. as just buying it from a United States based mail order company.  This is not
  21. free.  This program, and all my other software that is on Aminet, has now been
  22. marked to not be distributed on ANY of the Aminet CDs, unless and until the
  23. status of the 'free' CD for contributors becomes truely free again (i.e. at
  24. absolutely NO cost to me).
  25.  
  26.  
  27. What is it?
  28. ===========
  29.  
  30. AminetParse is a small utility to parse Aminet RECENT or INDEX lists into
  31. Thor's file database.  This is quite a bit faster than the arexx script
  32. supplied with Thor.  I experimented quite a bit with the arexx script, but
  33. the best I could get with it was approximately 22 files added per second.
  34. AminetParse is quite fast.  On my system, it reaches speeds in excess of 
  35. 150 files added per second.  In some cases I've seen it hit peaks of over
  36. 200 files per second!
  37.  
  38. RECENT/INDEX files can be filtered with the Sortmail.excl file, just like in
  39. Sortmail.  Also, as of AminetParse 1.05, a NewFiles.txt file will be created
  40. in the proper directory just like Sortmail does.  This will only be done on
  41. RECENT listings.  AminetParse does absolutely nothing with the NewFiles.txt
  42. file when parsing INDEX listings.  AminetParse will ignore any 'Message of
  43. the day:' that may be placed at the end of a RECENT listing.  I may change
  44. this in the near future to create a message in the email conference of Thor
  45. of the info contained within the 'Message of the day:' section.
  46.  
  47. Note: NewFiles.txt will be replaced completely every time AminetParse is
  48. run with a RECENT listing.
  49.  
  50. AminetParse requires Thor 2.3+ (at least ver 4 of bbsread.library) and 
  51. AmigaOS 2.04+.
  52.  
  53.  
  54. Installation
  55. ============
  56.  
  57. Well, it's real simple.  AminetParse is a cli-only program, and can be run
  58. from anywhere.  Probably the best place would be in the bin sub-directory
  59. of Thor's main directory.  Just copy it to wherever you want to run it
  60. from.
  61.  
  62. Just copy the AddAminet.thor script to Thor:rexx, and make sure AminetParse
  63. is in Thor:bin.  Then it can be run from within Thor whenever you want to
  64. parse a RECENT or INDEX listing into the database.
  65.  
  66.  
  67. Usage
  68. =====
  69.  
  70. AminetParse is a shell-only program.  If you try to start it from the
  71. Workbench, you will most likely crash your machine.
  72.  
  73. Just type AminetParse in a shell and you'll get output like this:
  74.  
  75. AminetParse 1.10 (24-May-99) © 1997-1999 Daniel J. Andrea II
  76. Usage:     AminetParse <system name> <INDEX/RECENT file> EXCLUDE QUIET
  77.  where <system name> is name of system to add files to
  78.        <INDEX/RECENT file> is full path and name of INDEX/RECENT file
  79.        EXCLUDE  (optional) tells AminetParse to use the Sortmail.excl file
  80.                 from inside the BBS's data directory to exclude certain file
  81.                 areas from being added to the database.
  82.        QUIET    (optional) turns off all console output while parsing files.
  83.  
  84. All you need is the name of your System in Thor, as in EMail&News (that's
  85. my BBS system name), and the full path and name of the INDEX/RECENT file.
  86. For example:
  87.  
  88.   AminetParse EMail&News SYS:temp/INDEX
  89.   
  90. will add the file INDEX from the drawer SYS:temp/ to the file database in
  91. the Thor system EMail&News.
  92.  
  93. Or add EXCLUDE:
  94.  
  95.   AminetParse EMail&News SYS:temp/INDEX EXCLUDE
  96.   
  97. will do the same as the previous example, but will use the Sortmail.excl
  98. file from inside the data directory of the BBS you enter.  If there is no
  99. Sortmail.excl file, AminetParse will continue as if the EXCLUDE option
  100. hadn't been entered along with a warning message.
  101.  
  102. If you add QUIET, it will turn off console output during parsing of the 
  103. files.  The final stats output will remain after parsing is complete.
  104.  
  105. The placement of the system name and INDEX/RECENT file name need to be
  106. in the order shown and immediately following the command name.  The EXCLUDE
  107. and QUIET options can be placed in any order after the file name.
  108.  
  109. That's it!
  110.  
  111. While AminetParse is running, you will get occasional status messages
  112. unless the QUIET option is enabled.  First it will tell you whether this
  113. is a RECENT listing, such as daily or weekly, or a full INDEX.  Then it
  114. will print out numbers periodically to show how many files have been
  115. processed.  Whenever a file area is parsed that is not in the file
  116. database, it will automatically add it and print out a message that it
  117. did so.
  118.  
  119. When it's finished, AmintParse will print out some statistics about the
  120. file parsing.
  121.  
  122. To parse listings while Thor is running, just execute the rexx script
  123. AddAminet.thor from the rexx menu.  It will check for the presence of
  124. a SortMail.excl file and prompt you if you want to filter with it.  
  125. AddAminet.thor will also prompt you to clear the file database if you are 
  126. parsing a full INDEX listing.
  127.  
  128. AminetParse now skips any extraneous data before the first real index listing
  129. line in the file.  So if you save the message to disk from Thor, you no longer
  130. need to edit out all the header information at the start of the file.
  131. AminetParse will check each line of text, starting from the beginning of the
  132. file, and checks to see if the line starts with the '|' character.  If it
  133. does, then it will check to see if the same line also contains either of the
  134. two words 'Complete' or 'Recent'.  If the line does not contain one of those
  135. words, it will scan to the end of file until it does find it.  If no start
  136. line for the listing is found, it will exit to the shell without doing
  137. anything to the database.
  138.  
  139.  
  140. Bugs
  141. ====
  142.  
  143. There are no known bugs at this time.  If you find any, please contact me
  144. at the E-Mail address or Snail-Mail address below with bug reports.  Be
  145. sure to include information on what other software was running and what
  146. kind of system you have.  Bug fixes will be incorporated into AminetParse
  147. as soon as possible.
  148.  
  149. PLEASE, please let me know if there is a problem with the parsing of a 
  150. particular file.  The 1.09 bug fix was probably long overdue, because I
  151. simply had not heard of the problem!  If there is a problem parsing an
  152. INDEX or RECENT listing from ANYWHERE, let me know and send a copy of it
  153. to me if possible.  It's the only way I can fix the problem!  Thanks.
  154.  
  155.  
  156. History
  157. =======
  158.  
  159.    v1.00  --  Initial release.
  160.  
  161.    v1.01  --  Added filtering based on the Sortmail script's filtering.
  162.               AminetParse uses the same file format, and will read the 
  163.               file Sortmail.excl from the BBS's data directory.
  164.    
  165.    v1.02  --  Well, it did have a bug.  Found my date calculation was
  166.               off by a couple of days.  Now shows correct date.
  167.  
  168.    v1.03  --  Added Checking for valid INDEX/RECENT file.  Removed a
  169.               warning message that wasn't needed.  Should fix some
  170.               problems noted by Trevor Daley.
  171.    
  172.    v1.04  --  Changed date calculation again.  This version should work
  173.               better now.
  174.  
  175.    v1.05  --  Added NewFiles.txt creation during parsing of RECENT
  176.               listings.
  177.  
  178.    v1.06  --  Fixed the parsing of weekly RECENT listings.  Previous
  179.               versions just treated all the files as being on the same
  180.               day.  Also will skip the 'Message of the day:' if it is
  181.               present in the RECENT listing.  The date parsing from the
  182.               listing should work properly on listings from other areas
  183.               (like from ftp.doc.ic.ac.uk), as long as the date is of the
  184.               form dd-mmm-yy or dd-mmm-yyyy, where dd is the day of the
  185.               month, mmm is the month name (like Sep for September), and 
  186.               yy or yyyy is the year (as in 97 or 1997).  Previous
  187.               versions would not work with listings that didn't originate
  188.               from the main Aminet site (ftp.wustl.edu).  It should now
  189.               work with listings from any site, but I cannot gaurantee
  190.               it will.  If anyone has a problem with an Aminet listing,
  191.               please send me a copy of the listing that caused a problem.
  192.               I can test it and release a bug fix as soon as possible from
  193.               that.
  194.    
  195.    v1.07  --  Just bumped the revision to reflect changes in the
  196.               documentation in relation to Aminet CDs as listed in the
  197.               beginning of this document.  No changes in the code itself.
  198.  
  199.    v1.08  --  Added QUIET option to shut off console output.  Makes parsing
  200.               of files a little faster.  Testing here on my new CyberStormPPC
  201.               board shows it about 3.5% faster with QUIET on.  Also re-worked
  202.               the argument parsing to allow for free placement of EXCLUDE
  203.               and QUIET after the file name.
  204.  
  205.    v1.09  --  Fixed parsing of RECENT listings from the uni-paderborn site.
  206.               I was not aware of the problem (which has been there since 1.06)
  207.               because nobody told me about it!  The problem came in how it
  208.               looked for the '-' character, which is in the middle of the 
  209.               site name from uni-paderborn first, instead of in the middle
  210.               of the date.  AminetParse now works on the INDEX listings I
  211.               have been receiving recently so should work for others as well.
  212.  
  213.    v1.10  --  Due to a recent system crash, the filesystem on my HD got trashed
  214.               and I lost the 1.08-1.09 source code.  I was able to re-write
  215.               this from scratch, and 1.10 is the result.  It works here the
  216.               same as 1.09 did.  No real difference, except I'm pretty sure
  217.               my technique this time around is a tad different than before.
  218.  
  219.  
  220. Author
  221. ======
  222.  
  223. I can be contacted through Internet E-Mail at:
  224.  
  225.       dandrea@tfs.net
  226.  
  227. or through Snail-Mail at:
  228.  
  229.       Daniel J. Andrea II
  230.       1331 Metropolitan St.
  231.       Leavenworth, KS 66048
  232.       U.S.A.
  233.  
  234. To check up on AminetParse development and other projects when they arise,
  235. point your web browser at
  236.  
  237.       http://www.tfs.net/~dandrea/
  238.  
  239. AminetParse was developed on a 25 MHz A3000 using SAS/C v6.57-6.58, and later
  240. on the same machine with a CyberStormPPC instead of the 68030.  :-)
  241.  
  242.  
  243. Future
  244. ======
  245.  
  246. Have you got an idea for improvement?  Let me know and I'll see what I can
  247. do.
  248.  
  249. Most likely I will be trying my hand at making an amigaguide version of this
  250. documentation for the next release.  I've never done it before, so I'll have
  251. to study up on it some.  ;)
  252.  
  253. Well, as you can see, I haven't done the Amigaguide version of this doc yet,
  254. but I have done it for MyFormat.  Next release of AminetParse will get an
  255. Amigaguide version.
  256.  
  257.  
  258. Thanks
  259. ======
  260.  
  261. Special thanks to Petter Nilsen of the Thor team for help with my early
  262. version of AminetParse.  I couldn't see the trees in the forest so to
  263. speak, and he helped me sort it out.  Thanks, Petter!
  264.  
  265. Also, thanks to Trevor Daley for pointing out the date calculation 
  266. problems in earlier versions.
  267.  
  268. Thanks to Neil Bothwick for the Arexx script.
  269.  
  270. Thanks to Jonas Thorell and Trevor Daley for pointing out the date problem
  271. with uni-paderborn RECENT listings.
  272.